Skip to content

feat: introduces "Sub-lobsters": nested lobster workflows with optional loop#20

Open
ggondim wants to merge 7 commits intoopenclaw:mainfrom
ggondim:main
Open

feat: introduces "Sub-lobsters": nested lobster workflows with optional loop#20
ggondim wants to merge 7 commits intoopenclaw:mainfrom
ggondim:main

Conversation

@ggondim
Copy link

@ggondim ggondim commented Feb 22, 2026

This pull request introduces support for sub-workflow steps in the workflow engine, allowing users to embed .lobster files as steps and optionally loop them with conditions, like a Ralph Loop. It adds new fields to the workflow step schema, updates validation logic, implements execution of sub-workflows (including looping and conditional exit), and provides comprehensive tests and documentation.

🚀 Sub-workflow step support

  • Added lobster, args, and loop fields to the WorkflowStep type, enabling steps to reference and run sub-workflows, pass arguments, and repeat execution with optional conditions. (src/workflows/file.ts src/workflows/file.tsR19-R31)
  • Implemented sub-workflow execution logic, including argument resolution, looping with max iterations and shell condition, and result propagation to parent workflow. (src/workflows/file.ts [1] [2]

🔰 Validation improvements

  • Updated workflow file validation to ensure lobster steps require a non-empty file path and that step IDs are unique. (src/workflows/file.ts src/workflows/file.tsR111-L105)

📝 Documentation updates

  • Added detailed documentation for new step fields and usage examples for sub-workflow steps and looping in README.md:

Step fields

Field Required Description
id yes Unique step identifier; used to reference the step's output in subsequent steps via $id.stdout or $id.json.
command yes (for regular steps) Shell command to run. Mutually exclusive with lobster.
lobster yes (for sub-workflow steps) Path to a .lobster file to run as a sub-workflow (resolved relative to the parent workflow). Mutually exclusive with command.
args no Key/value map of input arguments passed to the sub-workflow. Values support ${arg} and $stepId.stdout/$stepId.json template syntax. Only valid when lobster is set.
loop no Repeat the sub-workflow step in a loop. Only valid when lobster is set.
loop.maxIterations yes (when loop is set) Maximum number of iterations.
loop.condition no Shell command evaluated after each iteration. Exit code 0 continues the loop; non-zero stops it early. Receives LOBSTER_LOOP_STDOUT, LOBSTER_LOOP_JSON, and LOBSTER_LOOP_ITERATION as environment variables.
stdin no Pass a previous step's output as stdin.
approval no Set to required to insert an approval gate before the step runs.
condition no Expression that must be truthy for the step to run.

Sub-workflow step example

Use the lobster field to embed another .lobster file as a step in your workflow, optionally passing arguments and looping until a condition is met:

steps:
  - id: prepare
    command: echo "hello"
  - id: process
    lobster: ./sub_workflow.lobster
    args:
      input: $prepare.stdout
    loop:
      maxIterations: 10
      condition: '! echo "$LOBSTER_LOOP_STDOUT" | grep -q "^done"'

The sub-workflow's last step result (stdout/json) is stored as the step result and is accessible via $process.stdout / $process.json in subsequent steps.
134 changes: 129 additions & 5 deletions134
src/workflows/file.ts

✅ Testing

  • Added comprehensive tests covering sub-workflow execution, argument passing, looping behavior, loop conditions, and validation errors. (test/lobster_sub_step.test.ts test/lobster_sub_step.test.tsR1-R186)

Copilot AI and others added 7 commits February 22, 2026 22:13
Initial plan
c617ebd
@ggondim
Add kind: lobster sub-workflow step with loop support
1b9c103 
Co-authored-by: ggondim <2074685+ggondim@users.noreply.github.com>
@ggondim
Merge kind and file into single lobster property on WorkflowStep
927f7e5 
Co-authored-by: ggondim <2074685+ggondim@users.noreply.github.com>
@ggondim
Merge pull request #1 from ggondim/copilot/add-sub-lobster-command-step
3be1f1a 
Add `lobster` sub-workflow step with optional loop
Initial plan
8431fb5
@ggondim
docs: document lobster sub-workflow step in README
478900d 
Co-authored-by: ggondim <2074685+ggondim@users.noreply.github.com>
@ggondim
Merge pull request #2 from ggondim/copilot/document-lobster-step
56df8a5 
docs: document `lobster` sub-workflow step in README
@vignesh07
Copy link
Collaborator

vignesh07 commented Feb 24, 2026 •
edited
Loading

The primary upside of lobster is visibility and approval gating. Having an invisible sub loop running - especially compared to a Ralph loop concerns me.

I don't think this is the intended direction for lobster.

@ggondim
Copy link
Author

ggondim commented Feb 26, 2026

@vignesh07 Should Lobster be so opinionated and make the experience with deterministic workflows more challenging by imposing single-level-only workflows?

The arguments to merge it:

  • "Invisible sub loops running", including Ralph loops, are already possible: using exec commands or tools installed to OpenClaw.
  • Approval gates for "sub-lobsters" are still possible: users can use the condition config with previous approval gates or even nested ones

I understand if this doesn’t align with the team’s vision. Please let me know, and I’ll create a custom plugin for myself. Thank you for your time.

@costasx83
Copy link

costasx83 commented Feb 28, 2026

I would also agree and want this feature. i have gone through the same process to find something for autonmous coding and landed at the same end state. Otherwise no one will adopt lobster as a wokflow engine and build something else instead without this feature. Loops are a common pattern in any mature workflow engine and a great feature to have.

@IanHansonR
Copy link

IanHansonR commented Mar 5, 2026

Great feature, I have been planning a way to implement deterministic agentic flows and came across @ggondim article in DEV Community. Thank you for dedicating the time to make this feature. A valuable use case I have found for this is chaining smaller LLM's that are specialized for a specific niche of the problem at large. I am experimenting with 32b models that don't have great orchestration control but to make up for that I want code to link the agents. A linear track works in some use cases, but loops are essential to complex thought and evaluation chains.

I look forward to keeping up with this pull request and if the team decides it is not part of their vision I look forward to @ggondim custom plugin.

@ggondim
Copy link
Author

ggondim commented Mar 5, 2026

Hey @IanHansonR thanks for supporting this PR. While I await for the maintainers' response on it, I've created canonical-agents and duckflux. My last step this week will be a custom OpenClaw plugin to implement the duckflux runtime inside it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@ggondim @vignesh07 @costasx83 @IanHansonR